Creating a Supplier in QuickBooks

Overview

This document provides a detailed guide on how to create a supplier using Intuit's QuickBooks API. Once the supplier is successfully created, the vendor¹ ID will be retrieved and stored against the supplier as supplierFinanceId.

• Creation of supplier from DI Admin

• Creation of Supplier from Import Manager

For more info refer the Intuit's api docs for creating a vendor

Create a Supplier via QuickBooks API

1. API Endpoint:

   • Use the following endpoint to create a new supplier:

     POST /v3/company/{companyId}/vendor
   • Replace {companyId} with your actual company ID.

2. Request Payload:

• Structure your request payload in JSON format to include supplier details. For example:

  {
    "PrimaryEmailAddr": {
      "Address": "fuelgood@gmail.com"
    },
    "PrimaryPhone": {
      "FreeFormNumber": "018928343"
    },
    "DisplayName": "AV-Fuel Good Repairs",
    "Suffix": "",
    "Title": "",
    "Mobile": {
      "FreeFormNumber": ""
    },
    "FamilyName": "",
    "TaxIdentifier": "",
    "AcctNum": "dfdxsp8s0vKnaEPutrfd",
    "CompanyName": "AV-Fuel Good Repairs",
    "BillAddr": {
      "City": "Brighton",
      "Country": "UK",
      "Line3": "Somerset",
      "Line2": "East Sussex",
      "Line1": "12 Dyke Rd",
      "PostalCode": "BN13FE",
      "CountrySubDivisionCode": ""
    },
    "GivenName": "",
    "PrintOnCheckName": "Fuel Good Repairs"
  }

  This table shows how fields from ViSN are mapped to the QuickBooks API.

  Field in QuickBooks	Field from ViSN	Notes
  PrimaryEmailAddr.Address	Email	If email isn't provided, email will default to "visn.accounts@digitalinnk.com"
  PrimaryPhone.FreeFormNumber	Phone Number	Primary phone number of the supplier.
  DisplayName	Name	The supplier's name prefixed with AV-
  Suffix	NA	NA
  Title	NA	NA
  Mobile.FreeFormNumber	NA	NA
  FamilyName	NA	NA
  TaxIdentifier	NA	NA
  AcctNum	DI Supplier ID	Supplier ID from ViSN.
  CompanyName	Name	The supplier's name prefixed with AV-
  BillAddr.City	Town	Town from supplier's address
  BillAddr.Country	Country	Obtain the supplier's country based on its locale
  BillAddr.Line3	District	District from supplier's address
  BillAddr.Line2	Street Name	Street Name from supplier's address
  BillAddr.Line1	Building Number	Building Number from supplier's address
  BillAddr.PostalCode	Post code	Post code from supplier's address
  BillAddr.CountrySubDivisionCode	NA	NA
  GivenName	NA	NA
  PrintOnCheckName	Name	Name of the supplier to print on checks.

Handle the Response

1. Successful Response:

   • Response from Quickbooks API:

     • The API will return a JSON response containing the details of the newly created supplier, including the VendorId

     {
       "Vendor": {
         "BillAddr": {
           "Id": "1010",
           "Line1": "12 Dyke Rd",
           "Line2": "East Sussex",
           "Line3": "Somerset",
           "City": "Brighton",
           "Country": "UK",
           "PostalCode": "BN13FE"
         },
         "Balance": 0,
         "AcctNum": "dfdxsp8s0vKnaEPutrfd",
         "Vendor1099": false,
         "CurrencyRef": { "value": "GBP", "name": "British Pound Sterling" },
         "domain": "QBO",
         "sparse": false,
         "Id": "959",
         "SyncToken": "0",
         "MetaData": {
           "CreateTime": "2024-08-08T07:26:01-07:00",
           "LastUpdatedTime": "2024-08-08T07:26:01-07:00"
         },
         "CompanyName": "AV-Fuel Good Repairs",
         "DisplayName": "AV-Fuel Good Repairs",
         "PrintOnCheckName": "Fuel Good Repairs",
         "Active": true,
         "PrimaryPhone": { "FreeFormNumber": "0112312312" },
         "PrimaryEmailAddr": { "Address": "fuelgood@gmail.com" }
       },
       "time": "2024-08-08T07:26:01.345-07:00"
     }

   • Logging: The logs for successful creation of supplier are logged in logs/quickbooks/suppliers/{supplierId} ref in Firestore,

     

   • Linking the supplier to Quickbooks:

     • The VendorId from the response "Id": "959" will be stored against the supplier in Firestore as financeSupplierId.
       

2. Error Handling:

   • If the request fails, the API will return an error message, which is then handled and logged for troubleshooting

     • Logging: When an error occurs, the error details are logged to logs/quickbooks/suppliers/{supplierId} ref in Firestore.

       

     • Exception Handling: An exception is added to ancillaries/exceptions/suppliers/{accountId}-{supplierId} ref in Firestore for further analysis.

       

     • DI Admin: An error icon is displayed on DI Admin next to the affected supplier's name to indicate an issue.

       

Glossary

Vendor¹ In the context of ViSN, a vendor is equivalent to a supplier.

Status: Approved
Category: Protected
Authored By: Hadley on August 9, 2024